<!DOCTYPE html>
<!--[if IE 7]><html class="ie ie7" lang="en"><![endif]-->
<!--[if IE 8]><html class="ie ie8" lang="en"><![endif]-->
<!--[if IE 9]><html class="ie ie9" lang="en"><![endif]-->

<!--[if !IE ]><!-->
<html lang="en">
<!--<![endif]-->

<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1.0">
    <meta name="description" content="A detailed API documentation on KUTE.js public methods on how to create tween objects or how to control the tween animation.">
    <meta name="keywords" content="kute,kute.js,animation,javascript animation,tweening engine,animation engine,public methods,tween control,Javascript,Native Javascript,vanilla javascript,jQuery">
    <meta name="author" content="dnp_theme">
    <link rel="shortcut icon" href="./assets/img/favicon.png">
    <!-- TO DO -->

    <title>KUTE.js Developer API | Javascript Animation Engine</title>

    <!-- RESET CSS -->
    <link type="text/css" href="./assets/css/reset.css" rel="stylesheet">

    <!-- DEMO KUTE CSS -->
    <link type="text/css" href="./assets/css/kute.css" rel="stylesheet">

    <!-- Ion Icons -->
    <link type="text/css" href="http://code.ionicframework.com/ionicons/2.0.1/css/ionicons.min.css" rel="stylesheet">

    <!-- Synthax highlighter -->
    <link href="./assets/css/prism.css" rel="stylesheet">

    <!-- Polyfill -->
    <script src="./assets/js/minifill.js">
    </script>
    <!--[if lt IE 9]>
      <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <![endif]-->

    <!-- legacy browsers support via polyfill, you must remove the above when used
    <script src="https://cdn.polyfill.io/v2/polyfill.js?features=default,getComputedStyle|gated"> </script> -->

</head>

<body>
    <div class="site-wrapper">

        <div class="navbar-wrapper">
            <div class="content-wrap">
                <a href="index.html"><h1>KUTE.<span>js</span></h1></a>
                <ul class="nav">
                    <li class="btn-group"><a href="#" data-function="toggle">Features <span class="caret"></span></a>
                        <ul class="subnav">
                            <li><a href="features.html">Feature Overview</a></li>
                            <li><a href="properties.html">Supported Properties</a></li>
                        </ul>
                    </li>
                    <li class="btn-group">
                        <a href="#" data-function="toggle">Examples <span class="caret"></span></a>
                        <ul class="subnav">
                            <li><a href="examples.html">Core Engine</a></li>
                            <li><a href="css.html">CSS Plugin </a></li>
                            <li><a href="svg.html">SVG Plugin </a></li>
                            <li><a href="text.html">Text Plugin </a></li>
                            <li><a href="attr.html">Attributes Plugin </a></li>
                        </ul>
                    </li>
                    <li class="btn-group active">
                        <a href="#" data-function="toggle">API <span class="caret"></span></a>
                        <ul class="subnav">
                            <li><a href="start.html">Getting Started</a></li>
                            <li class="active"><a href="api.html">Public Methods</a></li>
                            <li><a href="options.html">Tween Options</a></li>
                            <li><a href="easing.html">Easing Functions</a></li>
                            <li><a href="extend.html">Extend Guide</a></li>
                        </ul>
                    </li>
                    <li><a href="about.html">About</a></li>
                </ul>
            </div>
        </div>


        <div class="content-wrap">
            <h2>Public Methods</h2>
            <p>These methods allow you to create <strong>tween objects</strong> and collections of <strong>tween objects</strong>; as we know, a tween object is essentially like an animation setup for a given HTML element, defining CSS properties, animation
                duration, repeat or other options. The methods have different uses and performance scores while making it easy to work with.</p>

            <h3>Single Tween Object</h3>
            <p>As the heading suggests, the following two methods allow you to create tween objects for individual HTML elements, except when used in combination with jQuery and the KUTE.js plugin for jQuery, where, as jQuery always does, it always works
                with collections of elements.</p>
            <p><kbd>.to()</kbd> method is the most simple method which allows you to create tween objects for animating CSS properties from a specific default value OR from current/computed value TO a desired value. It's performance is not the same as for
                the <strong>.fromTo()</strong> method as it has to compute the default/current value on tween <code>.start()</code> and thus delays the animation for a couple of miliseconds; still this feature is great for simple animations AND it has
                the ability to stack transform properties as they go, making smooth transform animations on chained tweens. See the <a href="#start">.start()</a> method for the solution for sync/delay issue.</p>
            <p>Considering a given <em>div</em> element is already transparent, a super quick example would be:</p>
            <pre><code class="language-javascript">KUTE.to(div,{opacity:1}).start()</code></pre>
            <p>As you might have guessed, this method is useful for creating simple animations such as for scroll, hide/reveal elements, or generally when you don't know the current value of the property you are trying to animate.</p>
            <p><kbd>.fromTo()</kbd> method is the best way to build animations for BEST performance and absolute control. The tests prove this method to be the fastest method but unlike the <code>.to()</code> method, it does not stack transform properties
                on chained tweens. Along with the performance advantage, you can set measurement units for both starting and end values, to avoid glitches. We've talked about this in the <a href="features.html">features page</a>. Here's a quick example:</p>
            <pre><code class="language-javascript">KUTE.fromTo(div,{opacity:1},{opacity:0}).start()</code></pre>

            <h3>Tween Object Collections</h3>
            <p>The two new methods allow you to create animations for multiple HTML elements at the same time, all in a single line of code. They use the above methods to create a tween object for each element of the collection and also enable the tween
                control methods in this new context.</p>
            <p><kbd>.allTo()</kbd> method allows you to create an array of tween objects for a collection of elements. This method is using the above <code>.to()</code> method and inherits it's functionality. Considering a given collection <code>myDivs</code>                elements, a nice example would be:</p>
            <pre><code class="language-javascript">// on the fly, grab the elements by className,
// do the tween objects array, and start kicking
KUTE.allTo( '.my-div-class', {opacity:1}, {offset: 200, duration: 500} ).start();

// or we cache the objects for better performance and / or later control
var myDivs          = document.querySelectorAll('.my-div-class');
var myDivsTweens    = KUTE.allTo( myDivs, {opacity:1}, {offset: 200, duration: 500} );
</code></pre>

            <p><kbd>.allFromTo()</kbd> method is also a method to animate a collection of elements and it uses the <code>.fromTo()</code> method. Quick example:</p>
            <pre><code class="language-javascript">KUTE.allFromTo( myDivs, {opacity:1}, {opacity:0}, {offset: 200, duration: 500} ).start()</code></pre>

            <p>As you can see the above code, these methods have a specific tween option called <code>offset</code> that allows you to set a delay in miliseconds between the starting time of each tween animation. Most tween control methods apply to both
                methods, except for the <code>.chain()</code> method. In order to chain another tween to one of the <code>myDivsTweens</code> objects, we would need to access it from the array, but let's leave that for later.</p>
        </div>

        <div class="content-wrap">
            <h2>Tween Control Methods</h2>
            <p>These methods allows you to control when the animation starts or stops. Let's write a basic tween object to work with the methods:</p>
            <pre><code class="language-javascript">var tween = KUTE.fromTo(div,{opacity:1},{opacity:0});</code></pre>
            <p>This tween object is now ready to work with the methods.</p>

            <h3 id="start">Starting Animations</h3>
            <p><kbd>.start()</kbd> method starts animation for a given tween object. It can start the animation for both cached and non-cached objects. Unlike previous versions of KUTE.js, where animation started immediately after tween object creation,
                now you have to manually start them. This method also applies to arrays of tween objects created with <code>.allTo()</code> and <code>.allFromTo()</code> methods.</p>
            <pre><code class="language-javascript">//cached object defined above
tween.start();

// non-cached object are created on the fly and garbage collected after animation has finised
KUTE.fromTo(div,{opacity:1},{opacity:0}).start();

// also start the tween at a certain time
tween.start(now); // where now must be the current or future time as number, see below

// lastly the method works with tweens made with .allTo() and .allFromTo() methods
KUTE.allFromTo(divs,{opacity:1},{opacity:0}).start();
KUTE.allTo(divs,{opacity:0}).start();
</code></pre>

            <p>As you can see, you can also set a time for the animation to start, example: <code>tween.start(myTimeValue)</code>. Having access to the method is useful when starting animation for large amounts of elements with same properties at the same
                time because using it properly <strong>eliminates any syncronization issue</strong> that may occur on animations start, even if you are using the <code>.to()</code> method. The trick is super duper simple:</p>

            <pre><code class="language-javascript">// step 1 - create an empty array and grab the elements to animate
var tweens = [], myElements = document.querySelector('.myManyElements'), numberOfElements = myElements.length;

// step 2 - define tween objects for each element
for (var i = 0; i < numberOfElements; i++) {
  var tween = KUTE.fromTo(myElements[i], fromValues, toValues, options);
  //now we populate the tweens array
  tweens.push(tween);
}

// step 3 - calculate the right time to start
// first we need the exact current time
var now = window.performance.now(); // this returns the exact current time in numeric format

// also we estimate/calculate an adjustment lag
// depending on the number of the elements AND hardware capability
// maybe (numberOfElements / 16) would be an accurate value for PCs
var lag = 100; // number of miliseconds for the script to built tween objects for all elements

// step4 - we just start the animation for all elements at once
for (var i = 0; i < numberOfElements; i++) {
  tweens[i].start(now+lag);
}
</code></pre>

            <p>In other cases the new methods <code>.allTo()</code> and <code>.allFromTo()</code> can be more useful.</p>

            <h3>Stopping Animation</h3>
            <p><kbd>.stop()</kbd> method stops animation for a given tween object or an array of tween objects (built with <code>.to()</code>/<code>.fromTo()</code> methods) while animating. You cannot stop the animation for tween objects created on the
                fly, only for cached objects. Let's assume that for the given tween we decide to stop the animation via <code>click</code> action:</p>
            <pre><code class="language-javascript">// for a tween object
stopButton.addEventListener('click', function(){
  myTween.stop(); // myMultiTweens.stop();
}, false);
</code></pre>

            <h3>Pausing Animation</h3>
            <p><kbd>.pause()</kbd> method freezez the animation at any given time for a given tween object or collection, and unlike the <code>.stop()</code> method, this one allows resuming the animation on a later use of the next method <code>.play()</code>.</p>
            <pre><code class="language-javascript">pauseButton.addEventListener('click', function(){
  tween.pause(); // or myMultiTweens.pause();
}, false);
</code></pre>

            <h3>Resuming Paused Animation</h3>
            <p><kbd>.play()</kbd> or <kbd>.resume()</kbd> methods allows you to resume an animation for a given tween object or collection of tweens, only if it was paused or else will produce no effect.</p>
            <pre><code class="language-javascript">playButton.addEventListener('click', function(){
  tween.play(); // or tween.resume(); || or myMultiTweens.resume();
}, false);
</code></pre>

            <h3>Chaining Tweens</h3>
            <p><kbd>.chain()</kbd> method can be used to chain tweens together. When the animation finishes for a given tween, it calls for <code>.start()</code> for another tween(s).</p>
            <pre><code class="language-javascript">var tween2 = KUTE.fromTo(div,{left:50},{left:0});

//the first tween chains the new tween
tween.chain(tween2);

//the new tween chains the first one creating a loop
tween2.chain(tween);
</code></pre>

            <p>It's also possible to chain multiple tweens, just as shown in the below example.</p>
            <pre><code class="language-javascript">//chain multiple tweens
tween.chain(tween1,tween2);
</code></pre>

            <p>Another thing we talked before is the ability to chain to one of the tween object within the array built with <code>.allTo()</code> or <code>.allFromTo()</code> methods.</p>
            <pre><code class="language-javascript">// chain to a tween from collection
var tweensCollection = KUTE.allTo('.a-class-for-multiple-elements', {opacity: 1});

// considering the collection has 5 tweens,
// the array is right here tweensCollection.tweens, so
// let's grab the second and chain another tween to it
tweensCollection.tweens[1].chain(tween2);
</code></pre>
            <p>Also we can chain the tweens created with <code>.allTo()</code> and <code>.allFromTo()</code> methods like this:</p>
            <pre><code class="language-javascript">// chain a collection of tweens to another tween
var tweensCollection2 = KUTE.allTo('.a-class-for-multiple-elements', {opacity: 1});

// the array is right here tweensCollection2.tweens
// we can pass it in the chain of another tween
tween2.chain(tweensCollection2.tweens);
</code></pre>
        </div>

        <div class="content-wrap">

            <ul id="share" class="nav">
                <li>Share </li>
                <li class="hidden-xs"><a target="_blank" href="https://www.facebook.com/sharer/sharer.php?u=http://thednp.github.io/kute.js/index.html" title="Share KUTE.js on Facebook"><span class="ion-social-facebook-outline icon"></span></a></li>
                <li class="hidden-xs"><a target="_blank" href="https://twitter.com/home?status=Spread the word about %23KUTEJS animation engine by @dnp_theme and download here http://thednp.github.io/kute.js/index.html" title="Share KUTE.js on Twitter"><span class="icon ion-social-twitter-outline"></span></a></li>
                <li class="hidden-xs"><a target="_blank" href="https://plus.google.com/share?url=http://thednp.github.io/kute.js/index.html" title="Share KUTE.js on Google+"><span class="icon ion-social-googleplus-outline"></span></a></li>
            </ul>

        </div>

        <!-- FOOTER -->
        <footer>
            <div class="content-wrap">
                <p class="pull-right"><a id="toTop" href="#">Back to top</a></p>
                <p>&copy; 2007 - 2016 &middot; <a href="http://themeforest.net/user/dnp_theme?ref=dnp_theme">dnp_theme</a>.</p>
            </div>
        </footer>

    </div>
    <!-- /.site-wrapper -->



    <!-- JavaScript
================================================== -->
    <!-- Placed at the end of the document so the pages load faster -->

    <!-- highlighter -->
    <script src="./assets/js/prism.js" type="text/javascript"></script>

    <!--<script src="http://cdn.jsdelivr.net/kute.js/1.6.0/kute.min.js"></script>  KUTE CDN -->

    <script src="./src/kute.min.js"></script>
    <!-- KUTE.js core -->
    <script src="./assets/js/scripts.js"></script>
    <!-- some stuff -->
</body>

</html>
